<!--

       Copyright 2006-2022 the original author or authors.

       Licensed under the Apache License, Version 2.0 (the "License");
       you may not use this file except in compliance with the License.
       You may obtain a copy of the License at

          https://www.apache.org/licenses/LICENSE-2.0

       Unless required by applicable law or agreed to in writing, software
       distributed under the License is distributed on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
       See the License for the specific language governing permissions and
       limitations under the License.


-->
<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html" />
  <title>MyBatis Generator Feature Debug Reference</title>
  <link type="text/css" rel="stylesheet" href="../mbgdoc/mbgstyle.css"/>
</head>
<body>
<h1>MyBatis Generator Feature Debug Reference</h1>
<p>This page contains reference information about how to build and debug the
MyBatis Generator (MBG) feature from source.</p>

<h2>Build Overview</h2>
<p>The feature is built using Eclipse Tycho - which is Maven support for Eclipse projects.
Tycho is a thin wrapper over the normal Eclipse PDE build processes.  Even though some of the projects
have a pom.xml, the projects are not structured like normal Maven projects.  Within Eclipse, 
you still need to use normal PDE support and editors to modify the feature. Do not try to import the
projects into your IDE as Maven projects - it will not work. The projects need to be imported as
regular Eclipse projects.</p>

<h2>Feature Structure</h2>
<p>There are eleven total projects that makeup the feature. Some projects are just for build support and testing.</p> 
<p>The published MBG feature is composed of five different Eclipse projects - a feature project,
and four plugin projects.
The feature project groups the four plugins together for easy installation.
Those projects are structured as follows:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Project</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>org.mybatis.generator</code></td>
    <td>This project is the Eclipse feature project for MBG.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.core</code></td>
    <td>This plugin holds the Java source for the core MBG library.
      Source from the core MBG source tree is copied into this plugin during the build.
      There is an Ant build file in this plugin (copySource.xml) that performs the copy.
      If you find a bug in the core MBG, you must make the correction in the
      core source tree - NOT this plugin.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.core</code></td>
    <td>This plugin holds Java support classes for the other plugins.  This plugin does not contribute
        to the Eclipse user interface.  This plugin includes classes for Java file
        merging, and Eclipse implementations of the MBG callback interfaces.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.doc</code></td>
    <td>This plug-in holds the documentation for MBG.  There is an Ant build file in this
      plugin (buildDoc.xml) that will build the documentation and package it for inclusion
      into the Eclipse help system.  The Ant script merges the core MBG documentation into
      the eclpse documentation.  If you need to correct something in the core MBG
      documentation, you must make the correction in the core MPB project - NOT the
      eclipse documentation project.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.ui</code></td>
    <td>This plug-in holds the Java code for the Eclipse user interface for MBG.  If you
      are experiencing trouble with the plugin specific features (like the integrated Ant task), then
      the code for those features will be found in this plugin.  An Ant script in this plugin 
      (copyDtds.xml) will copy the DTDs from the core MBG source tree into a location suitable for
      packaging in this plugin.
      <p>This plugin also contains a custom Ant builder for the Ant task.  This is required
      because of the way that eclipse accepts contributed Ant tasks - they need to be in a 
      separate JAR from the main plugin.</p>
    </td>
  </tr>
</table>

<h2>Other Projects</h2>
<p>There are six other Eclipse projects that are used in the build of the feature:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Project</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.site</code></td>
    <td>This project is a P2 publishing site that is used to publish the feature.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.core.tests</code></td>
    <td>This project is a plugin fragment that holds unit tests for the
        org.mybatis.generator.eclipse.core plugin.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.ui.tests</code></td>
    <td>This project is a plugin fragment that holds unit tests for the
        org.mybatis.generator.eclipse.ui plugin.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.test.utilities</code></td>
    <td>This project is a plugin that contains specialized AST visitors and custom
        Hamcrest (<a href="http://hamcrest.org">http://hamcrest.org</a>) matchers that are used in the test fragments for writing unit tests
        that cover the Java merge functionality.</td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.test.utilities.tests</code></td>
    <td>This project is a plugin fragment that holds tests for the
    org.mybatis.generator.eclipse.test.utilities plugin.</td>
  </tr>
  <tr>
    <td><code>releng</code></td>
    <td>This project is a simple project that holds other items useful during the build.</td>
  </tr>
</table>

<h2>Eclipse Workspace Setup</h2>
<p>The following instructions show how to setup an Eclipse workspace for building the MBG feature
and plug-ins from the latest source in the GitHub repository.  We assume that you are somewhat
familiar with git and the Eclipse plug-in development environment (PDE).</p>
<ol>
  <li>The authoritative source code for MyBatis Generator is on GitHub at
    <a target="_blank" href="https://github.com/mybatis/generator">https://github.com/mybatis/generator</a>.
    You can either fork the current source, or clone directly from the authoritative
    repository.  If you plan on submitting fixes or enhancements, you should fork the
    code into your own account.</li>
  <li>Clone the repository from GitHub. 
    <b>Note:</b> this will also checkout the source for the MBG core JAR which is required.
  </li>
  
  <li>Start Eclipse and make a new workspace</li>
  <li><b>Important:</b> make sure that a version 8.0 or higher JDK is available and visible to Eclipse
     (Window&gt;Preferences&gt;Java&gt;Installed JREs).  A JDK is required - a JRE
     alone will fail because of JavaDoc generation in the build and Tycho requires JDK 8.0 or above.</li>
  <li>Import the projects into the workspace
    <ol type="a">
      <li>Start the Eclipse project import wizard
        (File&gt;Import&gt;General&gt;Existing Projects into Workspace)
      </li>
      <li>Set the root directory to the "eclipse" sub-directory in your Git clone</li>
      <li>Select all eleven projects, do not copy the projects into
        your workspace.
        The filled out wizard looks similar to this: <br />
        <p><img src="importWizard.png" alt="Eclipse Project Import Wizard"/></p>
      </li>
      <li>Press "Finish", wait for the workspace to build.</li>
    </ol>
  </li>
  <li>The project includes an Eclipse target platform definition file. The purpose is to set the minimum version
   of Eclipse supported by the feature and to ensure that you do not inadvertently use Eclipse features from later
   versions. The file is <code>releng/target-platform-definition.target</code>. To activate
   the target platform, open the file and click on the link that says "Set as active target platform". This action
   may take a few minutes to complete.
  </li>
  <li>You will likely have workspace errors due to missing source code in the
    <code>org.mybatis.generator.core</code> project.  There are two ways to solve this:
      <ol type="a">
        <li>If you are comfortable with Maven, then you can run the Maven build by
          executing "./mvnw clean integration-test" on the <code>pom.xml</code> in the
          parent directory of all Eclipse projects (../eclipse)
          A slight warning: this will download many 
          dependent JARs from Maven central and eclipse.org the first time you run it.
          <p>This method is preferred because it runs the full build for all the
             plugins.  This will make is possible to debug all of the plugin
             features including documentation.</p>
        </li>
        <li>If you would rather not run the Maven build, you can run just run the
            <code>copySource.xml</code> Ant file in the <code>org.mybatis.generator.core</code>
            project.  This should resolve the build errors.
      </ol>
  </li>
</ol>

<h2>Debugging</h2>
<p>At this point the projects should be successfully compiled in Eclipse.  If you want to
  debug something in the plug-in, you will need to start another instance of Eclipse
  in debug mode.  The following instructions explain how to do this.</p>

<ol>
    <li>Set a breakpoint in the code you would like to debug.</li>
    <li>Double click on the "plugin.xml" file in the "org.mybatis.generator.eclipse.ui"
      project.  This should open the plug-in manifest editor.  If some other editor
      opens, then close the editor, right click on "plugin.xml" and select the
      "Open With&gt;Plug-in Manifest Editor" option.</li>
    <li>Select the "Overview" editor tab</li>
    <li>Take the option to "Launch an Eclipse Application in Debug mode".  This will
    start a new instance of Eclipse in debug mode with the MBG plug-ins installed.</li>
</ol>

<p>Once you have the other instance of Eclipse started you should create a new Java project
 in the new workspace, create and fill out an MBG configuration file, and then run MBG.
 MBG should eventually hit your breakpoint, and then you step through the code.
 Note that the "Manual Test Scripts" page in these instructions has instructions for creating
 a test project if you need one.</p>
<p>The following classes will likely be of the most interest in debugging:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Class</th>
    <th>Description</th>
  </tr>
  <tr>
    <td valign="top"><code>org.mybatis.generator.eclipse.ui.launcher.GeneratorLaunchConfigurationDelegate</code></td>
    <td>This class is used by eclipse launch support to execute a launch.  If you are
        experiencing a problem where the attributes you set in a launch configuration seen
        to be ignored or aren't working, you should set a breakpoint in the
        <code>launch</code> method of this class to follow the launch from the beginning.
        <p>Note that the launcher uses Ant under the covers, so this method simply sets up an
        Ant environment and launches Ant.  If you are experiencing issues in the core
        functionality of MBG, see below for a better staring point.</p> 
    </td>
  </tr>
  <tr>
    <td valign="top"><code>org.mybatis.generator.eclipse.ui.ant.GeneratorAntTask</code></td>
    <td>The MBG launcher uses Ant under the covers, and will eventually cause this task
      to be executed. You can set a breakpoint in the <code>execute</code> method of this
      class to follow the MBG code generation process from the beginning.
      <p>Note that eclipse will not be able to find the source code initially, so the
      debug window will just show a blank class file.  Add the <code>antsrc</code>
      directory in the <code>org.mybatis.generator.eclipse.ui</code> project
      to the source lookup path to solve that issue.</p>
    </td>
  </tr>
  <tr>
    <td><code>org.mybatis.generator.eclipse.core.merge.JavaFileMerger</code></td>
    <td>This class implements the Java file merge function.  You can set a breakpoint
      in the <code>getMergedSource</code> method to follow the merging process.
    </td>
  </tr>
</table>

<h2>Running the Unit Tests</h2>
<p>The plugin fragment project <code>org.mybatis.generator.eclipse.core.tests</code>
contains unit tests for many of the classes in the
<code>org.mybatis.generator.eclipse.core</code> project.
These tests cover the core functionality of Java code merging and workspace file resolution
that is an extra capability added by the eclipse feature.</p>
<p>The tests will be run during a maven build of the feature, but you can also run them
directly in eclipse. Running these unit tests is similar to running regular unit tests in
eclipse with the following exceptions:</p>
<ul>
  <li>The tests must be run with the eclipse plugin test runner.  So use the menu option
      Run As&gt;JUnit Plug-in Test.</li>
  <li>By default, the plugin test runner will start an instance of eclipse with the full UI.
      This can be quite slow and is unnecessary for the tests in this project.  To turn this off,
      follow these steps:
      <ol>
        <li>Open the run configuration for your test run (Run&gt;Run Configurations)</li>
        <li>Open the "main" tab</li>
        <li>Select the "Run an application" radio button</li>
        <li>Select "[No Application] - Headless Mode" in the drop down</li>
      </ol>
  </li>
</ul>
<p>To run all tests, run the class <code>org.mybatis.generator.eclipse.core.tests.RunAllTests</code>
which contains a test suite of all unit tests.
</p>

<h2>Building the Documentation</h2>
<p>The documentation for MBG is integrated into the Eclipse help system.
The documentation is partially generated (JavaDocs), partially copied in from the
core MBG source tree, and partially maintained in the plugin itself.
This full documentation set is not in source control because it is partially generated.  If you would
like to rebuild the documentation, simply execute the <code>buildDoc.xml</code> file
in the <code>org.mybatis.generator.eclipse.doc</code> project (an Ant build file).
This step is included in the Maven build, so if you are using the Maven build you will
not need to do this.
</p>

<h2>Building the Feature for Local Distribution</h2>
<p>If you want to build an updated version of the feature and distribute it locally, then
follow these steps:</p>
<ol>
  <li>Run the Maven build by running "./mvnw clean integration-test" in the parent directory of
      all projects (".../eclipse")</li>
  <li>Once the build completes the feature will be available in the <code>target/repository</code>
  directory of the <code>org.mybatis.generator.eclipse.site</code> project.</li>
</ol>

<p>After the build executes, the easiest way
to install this new version of the feature is to create a new local repository
that points to this directory (Help&gt;Install New Software...) and install
the new version with P2.</p>

<p>If you are interested in publishing a new version to JFrog, please see the
instructions on the <a href="publishing.html">Publishing</a> page.
</body>
</html>
